package com.zenithmind.exam.service;

import com.baomidou.mybatisplus.extension.service.IService;
import com.zenithmind.exam.pojo.entity.ExamStatistics;

import java.math.BigDecimal;
import java.util.List;

/**
 * 考试统计服务接口
 * 
 * @author ZenithMind
 * @since 2024-07-01
 */
public interface ExamStatisticsService extends IService<ExamStatistics> {

    /**
     * 更新考试统计信息
     * 
     * @param examId 考试ID
     * @return 更新结果
     */
    boolean updateExamStatistics(String examId);

    /**
     * 获取考试统计信息
     * 
     * @param examId 考试ID
     * @return 统计信息
     */
    ExamStatistics getExamStatistics(String examId);

    /**
     * 获取热门考试统计
     * 
     * @param limit 限制数量
     * @return 热门考试统计列表
     */
    List<ExamStatistics> getHotExamStatistics(Integer limit);

    /**
     * 获取高通过率考试统计
     * 
     * @param minPassRate 最低通过率
     * @param limit 限制数量
     * @return 高通过率考试统计列表
     */
    List<ExamStatistics> getHighPassRateExams(BigDecimal minPassRate, Integer limit);

    /**
     * 获取低通过率考试统计
     * 
     * @param maxPassRate 最高通过率
     * @param limit 限制数量
     * @return 低通过率考试统计列表
     */
    List<ExamStatistics> getLowPassRateExams(BigDecimal maxPassRate, Integer limit);

    /**
     * 获取总体统计信息
     * 
     * @return 总体统计信息
     */
    ExamStatistics getOverallStatistics();

    /**
     * 根据分数范围统计考试数量
     * 
     * @param minAvgScore 最低平均分
     * @param maxAvgScore 最高平均分
     * @return 考试数量
     */
    Integer countByAvgScoreRange(BigDecimal minAvgScore, BigDecimal maxAvgScore);

    /**
     * 获取最近更新的统计信息
     * 
     * @param limit 限制数量
     * @return 最近更新的统计信息列表
     */
    List<ExamStatistics> getRecentUpdatedStatistics(Integer limit);

    /**
     * 获取分数段统计
     * 
     * @return 分数段统计列表
     */
    List<ExamStatistics> getScoreRangeStatistics();

    /**
     * 批量更新需要更新统计的考试
     * 
     * @return 更新结果
     */
    boolean batchUpdateStatistics();

    /**
     * 生成考试统计报告
     * 
     * @param examId 考试ID
     * @return 统计报告
     */
    ExamStatistics generateStatisticsReport(String examId);

    /**
     * 删除考试统计信息
     * 
     * @param examId 考试ID
     * @return 删除结果
     */
    boolean deleteExamStatistics(String examId);

    /**
     * 重新计算所有考试统计
     * 
     * @return 重新计算结果
     */
    boolean recalculateAllStatistics();

    /**
     * 获取考试难度分析
     * 
     * @param examId 考试ID
     * @return 难度分析结果
     */
    String getDifficultyAnalysis(String examId);

    /**
     * 获取题目分析
     * 
     * @param examId 考试ID
     * @return 题目分析结果
     */
    String getQuestionAnalysis(String examId);

    /**
     * 获取分数分布
     * 
     * @param examId 考试ID
     * @return 分数分布结果
     */
    String getScoreDistribution(String examId);
}
